home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 038a / vegx20.zip / VGX.DOC < prev    next >
Text File  |  1990-11-15  |  16KB  |  376 lines
  1.                                VEGX
  2.                                 
  3.                  VGA and EGA Graphics file formats for
  4.                 QuickBASIC and Professional BASIC
  5.                            Programmers
  6.  
  7.                      Version 2.0, November, 1990
  8.  
  9.  
  10.                            USER MANUAL
  11.  
  12.  
  13.  
  14. Speed, speed, speed is what we want when loading a graphics file.  Second 
  15. only to speed is compressed file size.  Also desirable is ease of use.
  16.  
  17. Well, welcome to VEGX!  You have received an efficient, fast, and
  18. compressed VGA and EGA graphics file format for your QuickBASIC programs 
  19. that is remarkably easy to use.
  20.  
  21.  
  22. First, let's get a few preliminaries behind us:
  23.  
  24. LICENSE AGREEMENT:
  25.  
  26. All files on the VEGX distribution disk are (C) Copyright, 1990, Dwain 
  27. Goforth, Milestone Software, Arcata, California.  All rights reserved.
  28.  
  29. This software package (VEGX20.ZIP and associated files) is for review 
  30. purposes only.  No license is granted for distribution of this software or 
  31. software created using the VEGX object libraries.  The single exception to 
  32. this is that the original .ZIP distribution package may be distributed 
  33. provided no changes are made to any of the enclosed files.
  34.  
  35. The VEGX package comes with three types of files, 1) compiled object code 
  36. in libraries (files with the .LIB extension), 2) executable files 
  37. (PCX2VGX.EXE and VGXGRAB.COM), and 3) text and BASIC source code files 
  38. (with extensions of .DOC and .BAS)
  39.  
  40. Upon registration, you will be licensed to distribute executable (.EXE and 
  41. .COM) programs of your own creation that use the VEGX object modules.  No 
  42. royalties or copyright acknowledgement are required.  You will also be
  43. licensed to distribute PCX2VGX.EXE and VGXGRAB.EXE as long as they have 
  44. not been modified in any way.
  45.  
  46. You are prohibited from distributing the VEGX object files and their 
  47. associated libraries, or any library you make containing the VEGX object 
  48. files, unless you are transfering this license in its entirety and 
  49. removing all VEGX object files and any libraries containing them from your 
  50. computer system.
  51.  
  52.  
  53. WARRANTY:
  54.  
  55. Milestone Software makes no warranties or guarantees concerning use of 
  56. this shareware distribution package of VEGX.  Registered users will be 
  57. guaranteed 100% satisfaction with the version of VEGX which is sent to 
  58. them upon registration.  
  59.  
  60.  
  61. REGISTERING THIS SOFTWARE:
  62.  
  63. By purchasing registration for this software you will receive 1) a license 
  64. to distribute executable programs created with the VEGX object libraries, 
  65. 2) the most up to date version of the VEGX software, 3) full warranty, and 
  66. 4) additional files including PALCALLS.BAS, source code of nine pallete 
  67. utilities for VGA graphics programmers.
  68.  
  69. Registration costs $25.  Checks or money orders may be sent to Dwain 
  70. Goforth, Milestone Software, 1260 Sunset Ave., Arcata, California, 95521.
  71.  
  72.                       ----------------------------------
  73.  
  74. FILES ON THE VEGX DISK:
  75.  
  76. The following files are included on the VEGX distribution disk: 
  77.  
  78.      VEGX.DOC       -    This file, the VEGX manual.
  79.      VEGXSPEC.DOC   -    Specifications of the VEGX format.
  80.  
  81.      VEGX40.LIB     -    Library for QB 4.0 and BASIC 6.0.
  82.      VEGX45.LIB     -    Library for QB 4.5.
  83.      VEGX70N.LIB    -    Library for BASIC 7.0 using NEAR strings.
  84.      VEGX70F.LIB    -    Library for BASIC 7.0 using FAR strings.
  85.  
  86.      VGEX40.QLB     -    QB 4.0 and BASIC 6.0 quicklibrary.
  87.      VGEX45.QLB     -    QB 4.5 quicklibrary.
  88.      VGEX70F.QLB    -    BASIC 7.0 (QBX.EXE) quicklibrary (far
  89.                          strings.)
  90.  
  91.      EGXTEST.BAS    -    BASIC source code to demonstrate EGX.
  92.      VGXTEST.BAS    -    BASIC source code to demonstrate VGX and
  93.                          palette calls.
  94.      EGXVIEW.BAS    -    BASIC source code to view EGX files.
  95.      VGXVIEW.BAS    -    BASIC source code to view VGX files.
  96.  
  97.      PCX2EGX.EXE    -    Program to convert PCX to EGX.
  98.      PCX2VGX.EXE    -    Program to convert PCX to EGX.
  99.   
  100.      EGXGRAB.COM    -    TSR (memory resident) program to capture
  101.                          EGA SCREEN 9 (640x350x16) to an EGX file.
  102.      VGXGRAB.COM    -    TSR (memory resident) program to capture
  103.                          VGA SCREEN 12 (640x480x16) to a VGX file.
  104.  
  105.  
  106.                    ------------------------- 
  107.  
  108. INTRODUCTION - What is VEGX? 
  109.  
  110. VEGX are two new graphics file formats for use by QuickBASIC 4.x and BASIC 
  111. 7.0 programmers.  VGX supports ONLY the VGA 640x480 pixel 16-color 
  112. graphics mode (SCREEN 12), and because of this it is very fast. EGX is the 
  113. same for the EGA 640x350x16 SCREEN 9 mode.
  114.  
  115. If you've ever programmed EGA or VGA graphics files using the BASIC 
  116. BSAVE/BLOAD commands you know that even the least complex image requires 
  117. 153k of disk space in FOUR separate files (for VGA.)  Also, your palette 
  118. is not saved.  While BLOAD is fast, the file sizes, number of files and 
  119. lack of palette are enough to make one think twice before developing a VGA 
  120. or EGA image program in BASIC. 
  121.  
  122.  
  123. HOW DOES VEGX WORK?: 
  124.  
  125. VEGX is similar to BLOAD/BSAVE in that images are stored in "banks" just 
  126. like the VGA video memory stores them.  Each bank represents one color 
  127. (red, blue, green and intensity) and each bit in the bank is either on or 
  128. off and represents each pixel.  A VGA 640x480 16- color screen uses 152k 
  129. of video RAM with each bank using 38k. 
  130.  
  131. VEGX is similar to PCX in that it uses a "run-length" encoding scheme to 
  132. compress the data.  The PCX format compresses a screen one scan line at a 
  133. time (there are 480 scan lines in a VGA 640x480), while VEGX compresses an 
  134. entire bank at a time.  When a run of the same byte pattern is encountered 
  135. in a color bank, VEGX stores a count for them instead of the actual data.  
  136. Because banks are a series of 1's and 0's (on and off), the VEGX 
  137. compression of an entire bank is usually quite efficient.  VEGX switches 
  138. banks four times for each file, PCX switches banks four times for each 
  139. scan line (1920 times per file!) 
  140.  
  141. The VGA adapter stores the palette in 16 byte-triplets (one byte for each 
  142. color; 48 bytes total.)  VEGX simply gets this data from the VGA BIOS and 
  143. adds it to the VEGX file.  Included with the registered VEGX package is a 
  144. BASIC program, PALCALLS.BAS which will demonstrate the BIOS palette calls, 
  145. show how to "fade" the 48-byte palette data, and also how to rotate the 
  146. palette ("palette animation".)
  147.  
  148. The Save routines work by moving a VGA bank into RAM, compressing the data 
  149. into a an array and saving the compressed array as a temporary file.  This 
  150. is repeated three times, then the temporary files are appended together 
  151. along with the palette information.  The temporary files are then erased. 
  152. In the unlikely event that your computer crashes during a VEGXSave 
  153. session, you may find these temporary files on your directory 
  154. (filename.VX1 to filename.VX4). They can be erased.
  155.  
  156. Because VEGXSave copies an image of a bank and allocates an array to hold 
  157. the compressed data, VGXSave needs 74k of available RAM to work, while 
  158. EGXSave requires 56k of RAM.  This RAM is allocated at the beginning of 
  159. each VEGXSave call and released at the end of each call.
  160.  
  161. VEGXLoad works in an opposite manner to VGXSave; a 16k file-load buffer is 
  162. created as well as an 38k array to hold an uncompressed bank.  The 
  163. decompression algorithm works on one buffers worth of data at a time, 
  164. filling the bank array.  When a bank is full, it is transfered to video 
  165. RAM.  When a buffer is used up, another is gotten from the disk.  
  166. Depending on which option you choose to load a VGX image (fade-in, instant 
  167. on, etc...), the palette is processed before or after the actual load.
  168.  
  169. Because VGXLoad uses a 16k file buffer and a 38k bank array, VGXLoad 
  170. requires 54k of free RAM to work.  EGXLoad requires 44k of RAM (each bank 
  171. is 28k.)  This RAM is allocated at the start of each VGXLoad call and 
  172. released at the end.  The 16k buffer size was chosen as the optimum in a 
  173. tradeoff between loading speed and minimizing RAM use.  (An earlier, 
  174. pre-release version of VGXLoad had a self-allocating buffer of 2k to 64k, 
  175. but a "hard- wired" size proved to be faster.)
  176.  
  177. A number of algorithms were considered for the VGX compression. All of 
  178. them pose a tradeoff between compressed file size and speed of loading.  
  179. And while greater compression is obtainable, the vast superiority in speed 
  180. of the bank-load/run-length compression method left all other options in 
  181. the dust.
  182.  
  183.              -----------------------------------------
  184.  
  185.                            USING VEGX 
  186.  
  187. The VEGX file format is very easy to use in your QuickBASIC programs.  You 
  188. simply add VEGXxx.LIB to your normal quicklibrary or use the supplied VEGX 
  189. quicklibrary.  To create a stand-alone EXE file you link your program's 
  190. object file (created with BC) with VEGXxx.LIB. 
  191.  
  192. Once in QB, you simply CALL VGXSave (filname$) to save a file or CALL 
  193. VGXLoad (filname$, palflag%) to load a file. 
  194.  
  195. Libraries and Quicklibraries:
  196.  
  197. It is important to use the correct version of the VEGX library and
  198. quicklibrary for your version of QuickBASIC (or professional
  199. BASIC.)  If you have QB 4.0 or BASIC 6.0 please use VEGX40.LIB and
  200. VEGX40.QLB; if you have QB 4.5 please use VEGX45.LIB and VEGX45.QLB;
  201. and if you have BASIC 7.0 please use VEGX70.QLB in the QBX
  202. environment (far string quicklibrary) and VEGX70N.LIB to compile as
  203. near strings or VEGX70F.LIB to compile using far strings.
  204.  
  205. To load QB using the VEGX quicklibrary type "QB /L quicklibraryname"
  206. at the DOS prompt.
  207.  
  208. I have assumed that you already have your own personal library and
  209. quicklibrary to which you will want to add VEGXxx.LIB.  To do so,
  210. type the following at the DOS prompt:
  211.  
  212.      LIB yourname.lib +VEGXxx.LIB;
  213.      
  214.      LINK /q yourname.lib
  215.  
  216.      At the "Library" prompt type "BQLB40" if you have QB 4.0,
  217.      "BQLB41" if you have BASIC 6.0, "BQLB45" if you have QB 4.5
  218.      or "QBXQLB" if you have BASIC 7.0. (If you have BASIC 7.0
  219.      remember that you cannot make a near-string quicklibrary using
  220.      VEGX70N.LIB, you have use far strings in the QBX environment.)
  221.  
  222.  
  223. USING VGXSave and EGXSave:
  224.  
  225. Once in QB with a quicklibrary loaded containing VGX you may call VGXSave 
  226. and VGXLoad.  Prior to either call you MUST have entered VGA 640x480 
  227. 16-color graphics mode (SCREEN 12).  The syntax to call VGXSave is as 
  228. follows:
  229.  
  230.      CALL VGXSave(filnam$)
  231.  
  232. IMPORTANT!!! -->  Please note that "filnam$" DOES NOT include the
  233. extension, thus to make a VGX file named "TEST.VGX" you CALL
  234. VGXSave("test"), the extension will be added by VGXSave itself. 
  235.  
  236. Or...
  237.  
  238.      fil$="test"
  239.      CALL VGXSave(fil$)
  240.  
  241. You may also pass a path...
  242.  
  243.      fil$="C:\graphics\vgx\test"
  244.      CALL VGXSave(fil$)
  245.  
  246. To be on the safe side, your disk should have 153k of free space
  247. for the maximum size of any potential VEGX file.
  248.  
  249.  
  250. Using EGXSave is identical to VGXSave, except of course you must be in EGA 
  251. 640x350 16-color mode (SCREEN 9) and the file created will automatically 
  252. be given the EGX extension.
  253.  
  254. USING VGXLoad and EGXLoad:
  255.  
  256. The VGXLoad routine has two parameters and is called as follows:
  257.  
  258.      CALL VGXLoad(Fil$, Flag%)
  259.  
  260. Again, DO NOT use a filename extension for Fil$.
  261.  
  262. Flag% is the parameter to choose one of five loading options, from
  263. "instant on" to "fade-in".  
  264.  
  265. Flag% may range from 0 to 4.  The following table shows the action
  266. for the Flag% options:
  267.  
  268.           action for          action for
  269.           current             screen being
  270. Flag%     screen              loaded
  271. ----------------------------------------------
  272.   0       no blank            bank load
  273.   1       blank to color 0    instant on
  274.   2       blank to color 0    fade in
  275.   3       fade out            instant on
  276.   4       fade out            fade in
  277.  
  278. If Flag is 0 then the current image gets replaced one bank at a
  279. time, as soon as they are ready.  This is the fastest method to
  280. load a VEGX screen.  It is very much like BLOADing.
  281.  
  282. If Flag is 1 or 2 then the current image is cleared to its current
  283. background color (whatever color is assigned to attribute 0).  
  284.  
  285. If Flag is 3 or 4 then the palette for the current image is faded
  286. by changing each attribute closer to attribute 0 (color 0) in a 64
  287. count loop.
  288.  
  289. For the VEGX screen you are loading "instant on" is where the file
  290. is loaded into video RAM while all the colors are set to attribute
  291. zero and then DOS is called to set the actual palette that was
  292. stored in the file.  This method of setting the palette is very
  293. fast, much faster than using BASIC's PALETTE statements.  See
  294. PALCALLS.BAS for the syntax used in VGXLoad.
  295.  
  296. "Fade in" makes a 64 count loop, gradually changing the colors from
  297. attribute zero to their correct value.
  298.  
  299. Using EGXLoad is similar EXCEPT you only have two PalFlag% options, 0 or 
  300. 1.  When PalFlag% = 0 then the image will come on the screen one bank at a 
  301. time.  When PalFlag% = 1 then the screen will be cleared (all colors set 
  302. to zero, black) while the EGX file is loaded, then the pallete will be set 
  303. all at once after all the screen data is there.
  304.  
  305.  
  306. RUNNING PCX2VGX.EXE and PCX2EGX.EXE: 
  307.  
  308. If you have PCX files in 640x480 16-color format you can convert them to 
  309. VGX format using PCX2VGX.  PCX2VGX will convert the file, test load it, 
  310. and even test the gray-scale color balance (to see how your image will 
  311. look on a monochrome VGA display.) 
  312.  
  313. Please note that ONLY 640x480 16-color PCX files will convert correctly 
  314. with PCX2VGX and ONLY 640x350 16-color PCX files will convert with PCX2EGX.
  315.  
  316. Type `PCX2VGX filename' or 'PCX2EGX filename' at the DOS prompt, DO NOT 
  317. include any filename extension in `filename'. 
  318.  
  319.  
  320. RUNNING VGXGRAB.COM and EGXGRAB.COM: 
  321.  
  322. VGXGRAB and EGXGRAB are TSR (memory resident) programs that will dump 
  323. whatever is on your VGA 640x480 16-color (or EGA 640x350x16) screen to a 
  324. VGX or EGX file, respectively. Type VGXGRAB or EGXGRAB at the DOS prompt 
  325. and it will become resident. VGXGRAB will allocate approximately 80k of 
  326. RAM while resident (64k for EGXGRAB). Some paint programs that require a 
  327. full 640k to run will not run when VGXGRAB is resident (you will get an 
  328. "insufficient memory" error) In that event, hopefully, your paint program 
  329. will save to a PCX file format which you can then convert to VGX using 
  330. PCX2VGX. 
  331.  
  332. After VGXGRAB or EGXGRAB is resident, run whatever screen display program 
  333. you wish to capture from (VGXVIEW and VGXDEMO will work) and hit the 
  334. "hotkey" to save the image to a VGX format file.  The hotkey is CTRL/ENTER 
  335. (both the "Control" and "Enter" keys pressed at the same time.)  After the 
  336. VGX or EGX file is saved you will hear a short beep and control will 
  337. return to your display program.
  338.  
  339. VGX files saved by VGXGRAB are named VGXxxx.VGX where xxx is a number, so 
  340. the first VGX file you create with VGXGRAB will be VGX1.VGX, the second, 
  341. VGX2.VGX, and so on.  If a VGX file with the same name already exists, 
  342. that number will be skipped, so, for example, if VGX1.VGX and VGX2.VGX 
  343. already exist on the default directory, then the fist file VGXGRAB will 
  344. save is VGX3.VGX, etc...
  345.  
  346. EGXGRAB works the same way, only files are named EGXxxx.EGX where xxx is a 
  347. number.
  348.  
  349. VGXGRAB and EGXGRAB cannot be removed from memory.  In other words you 
  350. must reboot your computer to remove them.  I have attempted to create 
  351. removable TSR's (and will continue to try) but so far they are quite buggy 
  352. and I would rather be safe than sorry.
  353.  
  354. Please remember that VGXGRAB and EGXGRAB are designed specifically for the 
  355. 640x480x16 and 640x350x16 graphics modes.  Using them with other modes 
  356. will give unpredictable results.
  357.  
  358.                           - - - - - - -
  359.  
  360. In summary, remember you have three ways to create a VEGX file, 1) in QB 
  361. (or your compiled EXE) using VGXSave, 2) converting PCX files using 
  362. PCX2VGX, and 3) running the TSR program, VGXGRAB and capturing screens 
  363. while in another program. 
  364.  
  365.  
  366.                   --------------------------------
  367.  
  368. Thank you for trying VEGX.  Please feel free to call or write with any 
  369. questions or comments.
  370.  
  371. Dwain Goforth 
  372. Milestone Software 
  373. 1260 Sunset Ave. 
  374. Arcata, CA 95521 USA 
  375. (707) 822-1291 
  376.